<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>Routing - Fuel Documentation</title>
	<link href="../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../assets/js/nav.js"></script>
	<script type="text/javascript" src="../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('general', '../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>Fuel Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>Routing</h2>

		<p>Fuel's routing can range from simple static routes to advanced routes using HTTP verb based routing.</p>

		<p>Routes are set in <kbd>fuel/app/config/routes.php</kbd>.</p>

		<h3 id="reserved">Reserved Routes</h3>

		<p>In Fuel there are 2 reserved routes.	 They are <kbd>_root_</kbd> and <kbd>_404_</kbd>.</p>

		<ul>
			<li><kbd>_root_</kbd> - The default route when no URI is specified.</li>
			<li><kbd>_404_</kbd> - The route used when no controller or action can be found, can also be used as a
				catch-all route.</li>
		</ul>

		<pre class="php"><code>return array(
    '_root_'  => 'welcome/index',
    '_404_'   => 'welcome/404',
);</code></pre>

		<h3 id="basics">Basic Routing</h3>

		<p>The route on the left is matched the request URI and if it is matched then the request is routed to the URI on the right.</p>

		<p>This allows you to do things like the following:</p>

		<pre class="php"><code>return array(
    'about'   => 'site/about',
    'contact' => 'contact/form',
    'admin'   => 'admin/login',
);</code></pre>


		<h3 id="slightly_advanced">Slightly Advanced Routing</h3>

		<p>You can include any regex into your routes.	The left side is matched against the
		requests URI, and the right side is the replacement for the left, so you can use
		backreferences in the right side from the regex on the left.  There are also a few
		special statements that allow you match anything, or just a segment:</p>

		<ul>
			<li>:any - This matches anything from that point on in the URI</li>
			<li>:segment - This matches only 1 segment in the URI, but that segment can be anything</li>
		</ul>

		<p>Here are some examples:</p>

		<pre class="php"><code>return array(
    'blog/(:any)'      => 'blog/entry/$1', // Routes /blog/entry_name to /blog/entry/entry_name
    '(:segment)/about' => 'site/about/$1', // Routes /en/about to /site/about/en
);</code></pre>


		<h3 id="advanced">Advanced Routing</h3>

		<p>You can also have named parameters in your routes.  This allows you to give your URI segments
		names, which can then be accessed from within your actions.</p>

		<p>Example:</p>

		<pre class="php"><code>return array(
    'blog/:year/:month/:id' => 'blog/entry', // Routes /blog/2010/11/entry_name to /blog/entry
);</code></pre>

		<p>In the above example it would catch the following <kbd>/blog/2010/11/entry_name</kbd>.  It would then
		route that request to your 'entry' action in your 'blog' controller.  There, the named params
		will be available like this:</p>

		<pre class="php"><code>$this->param('year');
$this->param('month');
$this->param('id');</code></pre>


		<h3 id="http_verb">HTTP verb based routing</h3>

		<p>You can route your URLs to controllers and actions based on the HTTP verb used to call them.
		This makes it quick and easy to make RESTful controllers.</p>

		<p>Example:</p>

		<pre class="php"><code>return array(
    // Routes GET /blog to /blog/all and POST /blog to /blog/create
    'blog' => array(array('GET', new Route('blog/all')), array('POST', new Route('blog/create'))),
);</code></pre>

		<p>You can use named parameters and regexes within your URL just like normal:</p>

        <pre class="php"><code>return array(
    'blog/(:any)' => array(array('GET', new Route('blog/show/$1'))),
);</code></pre>

		<h3 id="module_routing">Modules &amp; Routing</h3>
		
		<p><a href="modules.html#module_routing">Read about how modules handle routing</a>.</p>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
